---
description: Backend Only mutations
keywords:
  - hasura
  - docs
  - permissions
  - rules
  - backend
sidebar_position: 70
---

import Thumbnail from '@site/src/components/Thumbnail';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Backend Only Mutations

## Introduction

Backend only permissions in Hasura allow certain mutations to be hidden from the public-facing API while still
accessible via a trusted backend. This is useful for operations that should bypass standard client-side validation or
business logic, ensuring that only authorized back-end services can perform these operations.

Setting "backend only" is available for `insert`, `update` and `delete` mutations.

<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">
Set a mutation permission for a role as backend only in the Hasura Console under **Data -> [table] -> Permissions ->
[role] -> insert / update / delete -> Backend only**
<Thumbnail
  src="/img/auth/allow-backends-only_console_2.10.1.png"
  alt="Allow backends only in Hasura Console"
  width="600px"
/>
</TabItem>
<TabItem value="cli" label="CLI">
Set a mutation permission for a role as backend only in the `metadata -> databases -> [database-name] -> tables ->
[table-name].yaml` file, e.g., `public_users.yaml`:

```yaml
table:
  name: users
  schema: public
insert_permissions:
  - role: user
    permission:
      check: {}
      columns:
        - id
      backend_only: true
delete_permissions:
  - role: user
    permission:
      backend_only: true
      filter: {}
```

</TabItem>
<TabItem value="api" label="API">

Set a mutate permission for a role as backend only with the Metadata API using the
[insert](/api-reference/syntax-defs.mdx#insertpermission), [update](/api-reference/syntax-defs.mdx#updatepermission), or
[delete](/api-reference/syntax-defs.mdx#deletepermission) permissions.

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
  "type": "pg_create_insert_permission",
  "args": {
    "table": {
      "name": "users",
      "schema": "public"
    },
    "role": "user",
    "permission": {
      "check": {},
      "columns": [
        "id"
      ],
      "set": {},
      "backend_only": true
    },
    "source": "default"
  }
}
```

</TabItem>
</Tabs>

:::info Supported from

Backend only permissions for update and delete mutations are supported in Hasura GraphQL Engine versions v2.8.0 and
above.

:::

## How it Works

### Scenarios

Backend only permissions create two operation modes within Hasura:

- Frontend Scenario: All mutation operations are visible when no backend-only permissions are set.
- Backend Scenario: Specific mutations set with backend-only permissions become visible only when the
  x-hasura-use-backend-only-permissions header is set to true.

### Schema Generation

Hasura maintains two GraphQL schemas per role per table:

| Schema Type         | Description                                                       | Example                                                                                                                                           |
| ------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Frontend Schema** | Visible mutations without backend-only permissions.               | Given a role "public" and a table "user", mutations like `insert_user` and `delete_user` are visible by default.                                  |
| **Backend Schema**  | Mutations visible only when backend-only permissions are enabled. | For the same role and table, the `update_user` mutation is only visible when the `x-hasura-use-backend-only-permissions` header is set to `true`. |

All operations are visible by default.

### Access Requirements

For a mutation to be accessible under backend only permissions, the following conditions must be met:

- `x-hasura-admin-secret` is present if authorization is configured.
- `x-hasura-use-backend-only-permissions` must be set to `true`.
- `x-hasura-role` is used to identify the role.

This table outlines the visibility of mutations based on the `Backend Only` permission along with the presence of
necessary headers:

| Backend Only | `x-hasura-admin-secret` | `x-hasura-use-backend-only-permissions` | Result         |
| ------------ | ----------------------- | --------------------------------------- | -------------- |
| FALSE        | ANY                     | ANY                                     | Always Visible |
| TRUE         | FALSE                   | ANY                                     | Always Hidden  |
| FALSE        | TRUE                    | ANY                                     | Always Visible |
| TRUE         | TRUE (OR NOT-SET)       | FALSE                                   | Hidden         |
| TRUE         | TRUE (OR NOT-SET)       | TRUE                                    | Shown          |
